Documentation build overview

📚 flexmeasures | 🛠️ Build #34023245 | 📁 Comparing 9b5af64 against latest (60cfda8)

  🔍 Preview build  

@BelhsanHmida — Felix reviewed the automations work and asked for one thing to land here: an automation administered through the UI (and hence the API) may only involve sensors that its creator can access. Could you review these commits, and then take the PR over again?

What we contributed:

• create_automation now works out which sensors an automation would read from and write to, and requires read access to the former and create-children on the latter — the same permission the API requires for recording data on a sensor. A refused request gets a 403 naming the sensor and the action, through the existing api_message mechanism.
• This is behind a check_permissions flag that the API passes; the CLI creates automations without a user and stays unrestricted.
• Forecasts: the sensor to forecast plus its regressors are inputs, the sensor to save to (the same sensor by default) is the output.
• Schedules: schedulers hand their results to make_schedule as (sensor, data) pairs, so the outputs are not only the flex-model's device sensors — a schedule is also recorded on a device's state-of-charge, consumption and production sensors, and on the flex-context's aggregate-consumption and aggregate-production. We derive the outputs from all of those fields at any depth, since the flex-model and flex-context are deserialized by the scheduler itself and their sensor references are still raw at this point. Everything else the parameters refer to (price sensors, inflexible-device sensors — these can live on the flex-context too) counts as an input.
• Tests cover both a forecast on another account's sensor and a schedule aggregated onto another account's sensor; both were verified to fail without the check. Docs, changelog and API change log updated.

Two things to be aware of:

1. This branch is ~108 commits behind its base, so it does not yet have the input_sensors / output_sensors properties we added to DataGenerator in Automations - first roundtrip for forecasts #2290. We kept the sensor resolution inside create_automation rather than duplicating those properties, so syncing the stack should be a small edit rather than a conflict — but the two should be collapsed into one implementation then.
2. Deriving output sensors statically is an approximation of what a scheduler actually returns at run time. If a scheduler starts writing somewhere else, this check will not know about it, so it is worth revisiting whenever a new output field is added.

🤖 Generated with Claude Code

Manual test walkthrough

Covers what CRUD adds over #2290 and #2293: administering automations through the API and the UI,
and the rule that you may only involve sensors you can access yourself. The responses below were
captured against a development database on this branch.

You need two logins to see the interesting half:

• an account admin (or consultant) on the asset — can create, edit and delete automations
• a plain user of the same organisation — can read automations, and is offered nothing that
  would change them

The examples use asset 242 (Campus, owned by the Campus Demo organisation) and its power sensor
913.

1. The page gains controls, for the right people

/assets/242/automations

As an account admin the listing gains a New automation button and per-row Edit,
Activate / Deactivate and Delete actions. As a plain user of the same organisation the
listing and its Details are unchanged, and none of those controls appear. Both are shown in the
PR description.

2. Create one from the UI

New automation asks for the name, the type, the recurrence, the timezone it is interpreted in,
and the parameters — forecast parameters for a forecast automation, or a schedule trigger message
for a schedule one. Create a forecast automation on sensor 913, daily at 06:00, in
Europe/Amsterdam, and it appears in the listing with its recurrence in words and its timezone.

3. The same over the API

# create
POST /api/v3_0/assets/242/automations
{
  "name": "Daily campus forecast",
  "type": "forecasts",
  "cronstr": "0 6 * * *",
  "timezone": "Europe/Amsterdam",
  "parameters": {"sensor": 913}
}
# → 201, with the automation, its timezone and its scheduling cursor

# change the recurrence, the timezone and the activation status
PATCH /api/v3_0/assets/242/automations/<N>
{"cronstr": "30 7 * * *", "timezone": "Asia/Seoul", "active": false}
# → 200

# delete
DELETE /api/v3_0/assets/242/automations/<N>
# → 204

The timezone is worth checking specifically: an automation created through the API used to be stuck
on the server's timezone, with only the CLI able to change it. Changing it also rebases the
scheduling cursor, so the automation does not immediately catch up on occurrences that only exist in
the new timezone's past.

Note that parameters cannot be patched. What an automation computes is fixed when it is created,
which is what keeps the access check below meaningful — the sensors it involves stay the ones its
creator was checked against.

4. You may only automate sensors you can access

This is the substance of the PR. As an account admin of one organisation, try to forecast a sensor
belonging to another. Sensor 426 below belongs to a different organisation than asset 242:

POST /api/v3_0/assets/242/automations
{"name": "Refused", "type": "forecasts", "cronstr": "0 6 * * *",
 "parameters": {"sensor": 426}}

HTTP 403
{
  "message": "You cannot set up an automation that would read data from sensor 426, because you cannot read data from it yourself.",
  "result": "Rejected",
  "status": "INVALID_SENDER"
}

A regressor that filters on sources is a sensor reference rather than a plain sensor, and is checked
just the same:

POST /api/v3_0/assets/242/automations
{"name": "Refused", "type": "forecasts", "cronstr": "0 6 * * *",
 "parameters": {"sensor": 913},
 "config": {"regressors": [{"sensor": 426, "source-types": ["forecaster"]}]}}

HTTP 403
{
  "message": "You cannot set up an automation that would read data from sensor 426, because you cannot read data from it yourself.",
  "result": "Rejected",
  "status": "INVALID_SENDER"
}

Three things are worth confirming while you are here:

• Nothing is created. The automation does not appear in the listing, and no data source is left
  behind for the forecaster it would have used — the data source is set up only once the automation
  is allowed.
• The message names the id, not the name. Refusing access should not disclose what a sensor you
  cannot read is called.
• Writing is checked separately from reading. Reading a sensor's data needs read access;
  recording data on one needs the same permission the API requires for recording data by hand.

For schedules the same applies to whatever the schedule would be recorded on, including sensors the
scheduler inherits from the asset tree rather than ones written out in the trigger message.

5. The CLI stays unrestricted

flexmeasures add automation --asset 242 --name "From the CLI" --cron "0 6 * * *" --sensor 913

The CLI runs without a user, so it is trusted and not subject to the check above. That is deliberate:
the restriction is about what a user may set up through the API or the UI.

6. Clean up

Delete anything you created, from the listing's Delete action or with
flexmeasures delete automation --id N --force.